home *** CD-ROM | disk | FTP | other *** search
/ TeX 1995 July / TeX CD-ROM July 1995 (Disc 1)(Walnut Creek)(1995).ISO / macros / lollipop / lollipop.hqx / Lollipop Manual / opt.tex < prev    next >
Text File  |  1992-11-18  |  16KB  |  472 lines
  1. % Opt.tex copyright 1992 Victor Eijkhout
  2. %
  3. \Chapter Options
  4.  
  5. This chapter discusses the various options that are common to all
  6. \Lollipop\ constructs.
  7.  
  8. \Section Titles
  9.  
  10. Any construct can have a title, although of course it is most useful
  11. for headings. 
  12. A construct has a title if the option \refopt{title} appears. 
  13. Example:
  14. \Ver>
  15. \DefineHeading:Section [...]
  16.     Style:bold title
  17.     [...] Stop<Rev
  18.  
  19. will define a \cs{Section} macro that has a title. 
  20. The macro is then used as
  21. \Ver>
  22. \Section The title of this section
  23.  
  24. Some text in this section.<Rev
  25. that is, the title is delimited by an empty line.
  26.  
  27. The title is actually available as a macro \refcs{FooTitle}, so that you
  28. can write a macro, for instance
  29. \Ver>
  30. \def\ComplicatedTitle{ .. \hrule ... 
  31.     \vrule ... \vbox \bgroup ...
  32.     \FooTitle ...
  33.     }<Rev
  34. and use this macro instead of the \opt{title} option
  35. \Ver>\DefineBar:Foo ...
  36.     ComplicatedTitle
  37.     ... Stop<Rev
  38. However, since the option \opt{title} now doesn't appear anymore, it
  39. becomes necessary to specify explicitly that there is a title.
  40. This can be done with the \refopt{HasTitle} option.
  41. \Ver>\DefineBar:Foo ...
  42.     HasTitle
  43.     ComplicatedTitle
  44.     ... Stop<Rev
  45.  
  46. \ImpNote
  47.  
  48. \iSection[imp:title:delimiting] Delimiting the title
  49.  
  50. The title is actually delimited by
  51. \cs{par}, so \Ver>\Section The title\par<Rev
  52. is allowed. Since delimiting by an empty line delimits by
  53. a space plus \cs{par} some extra measures are needed to get rid of the
  54. space in exceptional cases. The title is in effect augmented by
  55. \cs{unskip}. Thus, every time the title is typeset any trailing space
  56. is removed. See the definition of \cs{@Titelize} in
  57. section~\ref[imp:titelize].
  58.  
  59.  
  60. \iSection Is there a title?
  61.  
  62. The options \opt{title} and \opt{HasTitle} both set a test
  63. \cs{has@title} to true; this test is false by default
  64.  
  65. \Ver>\newif\ifhas@title\add@generic@default{\has@titleno}<Rev
  66.  
  67. The first of the two further causes inclusion
  68. of \cs{FooTitle} in the current option token list.
  69. \Ver>
  70. \@GenericOption{title}{
  71.     \global\has@titleyes
  72.     \ifin@label \label@append@title
  73.     \else \edef\cs@e{\nxp\@add@toks
  74.                  {\CSname{\@name Title}}}\cs@e
  75.     \fi}
  76. \@GenericOption{HasTitle}{
  77.     \switch {\if\EqualString{#1}}
  78.     {yes} {\global\has@titleyes}
  79.     {no}  {\global\has@titleno}
  80.     {default} {\global\has@titleyes}
  81.     \endswitch
  82.     }<Rev
  83.  
  84. Titles wind up in marks: at the end of defining \cs{Foo} the
  85. \cs{FooTitle} is added to the mark items.
  86.  
  87. \Ver>
  88. \add@generic@stop@default
  89.    {\ifhas@title\xp\add@mark@item\xp{\@name Title}\fi}<Rev
  90.  
  91. \iSection[imp:titelize] Giving a macro a title
  92.  
  93. Lollipop macros are first defined without titles. If necessary they
  94. are then redefined to have a title.
  95.  
  96. The redefinition
  97. depends on how many arguments the macro originally had; this is
  98. determined by a counter \cs{extra@args}.
  99.  
  100. \Ver>\newcount\extra@args \add@generic@default{\extra@args\z@}<Rev
  101.  
  102. At present, only external items (section~\ref[sec:ext-item]) have extra
  103. arguments.
  104.  
  105. The redefinition proceeds by storing the original definition
  106. in \cs{tit@Foo}, the macro is then redefined as a macro with an
  107. extra argument, which is stored in \cs{title@toks}. 
  108. Often it is convenient to have the title in a token list to prevent it
  109. from being expanded. 
  110.  
  111. Additionally, an \cs{unhskip} is appended to the title, because
  112. delimiting with an empty lines will give a space before the delimiting
  113. \cs{par}.
  114.  
  115. \Ver>
  116. \def\@Titelize#1{%
  117.     \edef\cs@e{\let\CSname{tit@#1}=\CSname{#1}}\cs@e
  118.     \ifcase\extra@args %0:
  119.         \csarg\edef{#1}##1\par
  120.              {\title@toks{{##1\nxp\protect\nxp\unhskip}%
  121.               \CSname{tit@#1}}
  122.     \or %1:
  123.         \csarg\edef{#1}##1##2\par
  124.              {\title@toks{##2\nxp\protect\nxp\unhskip}%
  125.               \CSname{tit@#1}{##1}}
  126.     \or %2:
  127.         \csarg\edef{#1}##1##2##3\par
  128.              {\title@toks{##3\nxp\protect\nxp\unhskip}%
  129.               \CSname{tit@#1}{##1}{##2}}
  130.     \else \Wmessage{Sorry, too many extra arguments 
  131.                     for `\@class' : `\@name'}
  132.     \fi}<Rev
  133.  
  134. \iSection[imp:install:title] Storing the title
  135.  
  136. In \cs{outer@start@commands} the title is then put in the macro
  137. \cs{FooTitle}.
  138.  
  139. \Ver>\def\install@title@code
  140.    {\nxp\xp\def\nxp\xp\CSname{\@name Title}\nxp\xp{%
  141.            \nxp\xp\nxp\maybe@uppercase\nxp\xp
  142.                  {\nxp\the\title@toks}}%
  143.     \ifhas@marks \edef\nxp\cs@e
  144.              {\nxp\nxp\nxp\refresh@mark@item
  145.                {\@name Title}{\nxp\the\title@toks}}%
  146.             \nxp\cs@e
  147.     \fi}<Rev
  148.  
  149. This piece of code is inserted after any page break, because it
  150. refreshes the mark information. Furthermore, its inclusion is
  151. conditional.
  152.  
  153. \Ver>    \ifhas@title \install@title@code
  154.     \fi<Rev
  155.  
  156. \ImpNoteStop
  157.  
  158.  
  159. \Section[sec:opt:counter] Counters
  160.  
  161. There are three ways for Lollipop to figure out that a generic
  162. construct has a counter. First of all, in
  163. \Ver>\DefineFoo:Bar [...]
  164.     BarCounter [...]<Rev
  165. the \cs{BarCounter} will be defined automatically.
  166.  
  167. Additionally there is the option \refopt{counter}, which can be used
  168. to declare the representation of the option, for instance
  169. \opt{counter:i} allocated a counter that is printed in lowercase roman
  170. numerals. For the available representations,
  171. see~\ref[sec:counter:repr].
  172.  
  173. Finally, if the counter is only used in a macro, the
  174. option \refopt{HasCounter} will cause the counter to be created anyhow.
  175. This is analogous to the \opt{HasTitle} option.
  176.  
  177. \SubSection Counter synonyms
  178.  
  179. Every once in a while you may want different constructs to use the same
  180. counter. For instance, if your book has definitions, theorems, lemmas,
  181. corollaries and notations, it may confuse the reader if they all have
  182. their own counter. The numbering would seem to jump all over the place.
  183.  
  184. A `counter synonym' can be declared in \Lollipop\ by a slight abuse of
  185. the \opt{counter} option.
  186. \Example
  187. \DefineTextBlock:Theorem counter:1 begingroup Style:bold
  188.  literal:Theorem Spaces:1 TheoremCounter Spaces:2 endgroup
  189.  text Stop
  190. \DefineTextBlock:Corollary counter:Theorem begingroup Style:italic
  191.  literal:Corollary Spaces:1 CorollaryCounter Spaces:2 endgroup
  192.  text Stop
  193. \DefineTextBlock:Definition counter:Theorem begingroup Style:roman
  194.  literal:Definition Spaces:1 DefinitionCounter Spaces:2 endgroup
  195.  text Stop
  196. \Definition We define a {\it Foo} to be an arbitrary object\>
  197. \Theorem Foos have arbitrary properties\>
  198. \Corollary Foos are extremely valuable\>
  199. \Corollary Foos are extremely worthless\>
  200. \Theorem Foos don't exist\>
  201. \ExampleStop
  202.  
  203. You can only declare a counter to be synonym for something that has
  204. already been created. In the above example you cannot define the
  205. \cs{Theorem} after the \cs{Corollary}.
  206.  
  207. \ImpNote
  208. At the start of defining the construct, \cs{BarCounter} is defined to
  209. be an option:
  210. \Ver>\add@generic@default{\has@counterno
  211.     \def\counter@repr{1}
  212.     \csarg\def{\gen@option@name{\@name Counter}}{%
  213.         \@add@toks{\@name Counter}\global\has@counteryes}}<Rev
  214.  
  215. Then,
  216. \Ver>\add@generic@stop@default{\ifhas@counter
  217.     \xp\expandafter\xp\install@counter
  218.            \xp\counter@repr\@space\fi}<Rev
  219.  
  220.  
  221. The counter is stepped, and the new value is stored in a mark item,
  222. in \cs{outer@start@commands}:
  223.  
  224. \Ver>
  225.     \ifhas@counter 
  226.        \nxp\StepCounter:\expandafter\@name\@space
  227.        % This sets the \current@label by default
  228.        \ifhas@marks \edef\nxp\cs@e
  229.               {\nxp\nxp\nxp\refresh@mark@item
  230.                 {\@name Counter}{\CSname{\@name Counter}}}%
  231.             \nxp\cs@e      
  232.        \fi
  233.        \fi<Rev
  234. \ImpNoteStop
  235.  
  236. \Section Chunks of text
  237.  
  238. Especially in headings, short chunks of text may need a special
  239. treatment. For instance, the number may have to be filled to a certain
  240. width, or a line may have to be drawn of the exact length of the
  241. title. Lollipop have various general options (so they can also be used
  242. in other contexts than headings) for handling pieces of text.
  243.  
  244. \SubSection[sec:opt:block] The \opt{block} option\label[opt:block]
  245.  
  246. The \refopt{block} option takes up a piece of text and fits it on one
  247. line. It can measure the text, or set the size. Also there are a number
  248. of ways of placing a block.
  249.  
  250. Basic usage:
  251. \Ver>    block:start [...] block:stop<Rev
  252. This takes the enclosed text, and reproduces it. This is mostly
  253. interesting in combination with \opt{textcolumn},
  254. see~\ref[sec:opt:textcolumn].
  255. \Ver>    block:hang [...] block:stop<Rev
  256. The resulting block is dropped until its top touches the baseline.
  257. For uniformity of appearance, the resulting width of the block can be
  258. specified:
  259. \Ver>    block:start [...] fillupto:20pt<Rev
  260. The name of a \cs{Distance} parameter can be used here.
  261.  
  262. \Example
  263. \DefineHeading:TestHeading
  264.  line:start block:hang PointSize:8 SetFont 
  265.                   TestHeadingCounter fillupto:20pt
  266.             block:hang PointSize:14 SetFont title block:stop
  267.  line:stop Stop
  268. \TestHeading Top Aligning the Title
  269.  
  270. \endExample
  271.  
  272. The block is usually in between the margins of the text, but it can be
  273. made to stick out into the margin, by closing it with the option
  274. \refopt{stickout}.  For the left margin this done as
  275.  \Ver>    block:start [...] stickout:left<Rev
  276. and for the right margin
  277.  \Ver>    block:start [...] stickout:right<Rev
  278. The size of the box can be specified, for instance as
  279.  \Ver>    block:start [...] stickout:left=20pt<Rev
  280. For a left box the material in it is pushed to the left edge, for a
  281. right sticking box it is shifted to the right.
  282.  
  283. \SubSection[sec:blockwidth] Block Measuring
  284.  
  285. All blocks are immediately measured when they are placed. This makes it
  286. possible for instance to underline a title exactly. After a block has
  287. been placed, its width is available as \refcs{BlockWidth}.
  288.  \Example
  289. \def\rulespecs{height 1pt width \BlockWidth\relax}
  290. \DefineHeading:TestHeading Style:bold
  291.  line:start block:start TestHeadingCounter . Spaces:2 stickout:left
  292.             block:start title block:stop line:stop
  293.  vwhite:2pt hrule rulespecs vwhite:10pt Stop
  294. \TestHeading The Title Is Underlined
  295.  
  296. The text follows.
  297. \ExampleStop
  298. Observe how a control sequence \cs{rulespecs} is used to sneak the
  299. height and width of the rule into the definition. This is necessary
  300. because control sequences are not allowed in a construct definition.
  301.  
  302. \SubSection[sec:opt:line] The \opt{line} option
  303.  
  304. The option \refopt{line} is used to create a single strip of text that
  305. fits exactly in between the margins of the page. Most of the time, titles
  306. will be in a line. 
  307.  
  308. \Example
  309. \DefineHeading:TestHeading
  310.     line:start block:start TestHeadingCounter Spaces:1.5 stickout:left
  311.                title line:stop Stop
  312. \TestHeading A Title
  313.  
  314. \endExample
  315.  
  316. Another example was above. Here is another use of a line:
  317.  
  318. \Example
  319. \DefineHeading:TestHeading
  320.     line:start TestHeadingCounter fillup title line:stop Stop
  321. \TestHeading The title
  322.  
  323. \endExample
  324.  
  325. \SubSection[sec:opt:textcolumn] The \opt{textcolumn} option
  326.  
  327. In the examples above all titles fit on one line comfortably. If this
  328. is not the case, the title can be put in a \refopt{textcolumn} which can
  329. span several lines.
  330.  
  331. \Example
  332. \DefineHeading:TestHeading
  333.     line:start block:start TestHeadingCounter Spaces:2 block:stop
  334.                textcolumn:topline title textcolumn:stop
  335.     line:stop Stop
  336. \TestHeading A very very very very very very very very very very very
  337. very very very very very very very very very very very very very
  338. very very very very very very very very long title
  339.  
  340. \endExample
  341.  
  342. This option is mostly interesting in combination with others such as
  343. \opt{block} and \opt{line}. As is apparent from the above example: a
  344. block placed in the same line as a text column will detract from the
  345. latter's width. 
  346.  
  347. (In fact it is the other way around: \Lollipop\ sets
  348. the line with a text column of width zero to determine the remaining
  349. space. Then the line is set again. This may give problems if you
  350. manipulate parameters inside the line, because the line is in effect
  351. typeset twice. Also make sure not to have other \cs{vbox}-es in the
  352. line than the text column.)
  353.  
  354. \SubSection[sec:opt:traps] Traps
  355.  
  356. It is a bad idea to have material in headings and such that is not
  357. inside a block, textcolumn, or line. For instance:
  358.  
  359. \Example
  360. \DefineHeading:TestHeading
  361.     block:start TestHeadingCounter Spaces:2 block:stop
  362.     title Stop
  363. \TestHeading Where does the title go?
  364.  
  365. \endExample
  366.  
  367. \Section[sec:opt:label] Labels
  368.  
  369. References to any counter will always be correct, no matter if that
  370. counter has changed after retypesetting the document, if symbolic
  371. references are used. Referencing is explained in detail in
  372. chapter~\ref[chap:referencing].
  373.  
  374. The way a symbolic reference is formatted can be altered from the
  375. default (just give the counter) by using the \refopt{label} option.
  376. \Ver>\DefineHeading:TestSection
  377.  line:start Style:italic TestSectionCounter Spaces:2 title line:stop
  378.  label:start ( TestSectionCounter ) label:stop Stop<Rev
  379. See further section~\ref[sec:shape:reference].
  380.  
  381.  
  382. \Section[sec:opt:penalties] Break before / after
  383.  
  384. The options \refopt{breakbefore} and \refopt{breakafter} control how
  385. eager \TeX\ will be to break the page before or after a construct. These
  386. options take one value, a so-called `penalty' value, meaning that the
  387. higher the value you specify, the higher the penalty is, and
  388. therefore the less likely it is that the page will be broken there.
  389.  
  390. Numerical values are typically in the tens or hundreds; any value
  391. of \n{10$\,$000} or more means that there will never be a break at
  392. that point; a value of \n{-10$\,$000} or less means a guaranteed
  393. break. If you don't want to remember these rules, values of \n{yes}
  394. and \n{no} mean a guaranteed break, and no break respectively.
  395.  
  396. \WizNote
  397. A further exceptional value is \n{breakbefore/after:0}, this will
  398. cause no penalty to be placed. The reason for this is highly \TeX
  399. nical.
  400. \>
  401.  
  402. \Section[sec:opt:indent] Indentation
  403.  
  404. The option \refopt{indentafter} controls the behaviour of the first
  405. paragraph after a generic construct., \refopt{indentinside},
  406. \refopt{indentfirst}.
  407.  
  408. \Section Rules
  409.  
  410. There is an option \refopt{hrule}. You should not write
  411. \Ver>\def\rulemacro{\hrule height [...] }
  412. \DefineHeading [...] rulemacro [...] Stop<Rev
  413. because then \Lollipop\ cannot prevent page breaks around the rule.
  414. Instead write 
  415. \Ver>\def\rulespecs{ height [...] }
  416. \DefineHeading [...] hrule rulespecs [...] Stop<Rev
  417. so that the option \opt{hrule} is used. See
  418. section~\ref[sec:blockwidth] for an example.
  419.  
  420. \Section Embedded constructs
  421.  
  422. Most generic constructs will be vertically separated from the
  423. surrounding text. However, in rare cases (and for unusual applications)
  424. it be desired to have a construct that is part of a paragraph. For this
  425. the option \refopt{embedded} exists.
  426.  
  427. This option has the following values.
  428. \Ver>    embedded:no<Rev
  429. This is the default.
  430. \Ver>    embedded:left<Rev
  431. The construct continues an already started paragraph, but after the
  432. construct a vertical break follows.
  433. \Ver>    embedded:right<Rev
  434. After the construct a paragraph can continue, but the construct is
  435. separated vertically from preceding text.
  436. \Ver>    embedded:yes<Rev
  437. The construct is both left and right embedded.
  438.  
  439. Embedding a construct has an interesting application to generating
  440. indexes. (See chapter~\ref[chap:external-files] for general information
  441. about external files.) This can be done by having embedded headings
  442. that write their title to the index file.
  443.  
  444. \Example
  445. \DefineExternalFile:tIndex=tix
  446. \DefineHeading:NewWord embedded:yes 
  447.  block:start Style:bold title block:stop
  448.  external:tIndex title external:stop Stop
  449. \def\introword#1{\NewWord #1\par}
  450. In this sentence two \introword{flubrious} words are
  451. \introword{stinselsed}.
  452. \ExampleStop
  453.  
  454. Cute, ain't it?
  455.  
  456. \Section[sec:implicit:close] Implicit closing
  457.  
  458. The control sequence \refcs{>} closes the current group, and \refcs{>]}
  459. closes all currently open groups. Every once in a while this is too
  460. drastic. Hence there is an option \refopt{noimplicitclose} that can be
  461. used to prevent a construct from being closed implicitly.
  462.  
  463. \Section[sec:opt:test] Testing
  464.  
  465. There is an option \opt{test}.
  466.  
  467. \endinput
  468.  
  469. 92/11/10 \BlockWidth discussed in 'block' section
  470. 92/11/15 counter:othercounter discussed
  471.  
  472.